Migration Guide: From MAX to XMediator
Integration
This section helps you migrate from the AppLovin MAX SDK to the XMediator SDK in your iOS project.
Initialize the SDK Comparison
- Swift
- Objective-C
| Operation | MAX | XMediator |
|---|---|---|
| SDK Initialization | ALSdk.shared().initialize(...) | XMediatorAds.startWith(appKey:initSettings:...) |
| Set User ID | settings.userIdentifier = "user-id" | UserProperties(userId: "user-id") |
| Set Test Mode | builder.testDeviceAdvertisingIdentifiers = [...] | InitSettings(test: true) |
| Set Extra Params | setExtraParameterForKey("key", value) | InitSettings(userProperties: UserProperties(customProperties: ...)) |
| Operation | MAX | XMediator |
|---|---|---|
| SDK Initialization | [[ALSdk shared] initializeWithConfiguration:...] | [X3MXMediatorAds startWithAppKey:initSettings:callback:] |
| Set User ID | settings.userIdentifier = @"user-id"; | userProperties.userId = @"user-id"; |
| Set Test Mode | builder.testDeviceAdvertisingIdentifiers = @[...]; | initSettings.test = YES; |
| Set Extra Params | [ad setExtraParameterForKey:value:]; | initSettings.userProperties.customProperties = ...; |
Optional Configuration
| Feature | MAX | XMediator |
|---|---|---|
| Set User ID | settings.userIdentifier = "user-id" | UserProperties(userId: "user-id") |
| Extra Parameters (e.g., tokens) | setExtraParameterForKey("uid2", ...) | InitSettings (passed during init) |
| Enable Logging | settings.isVerboseLogging = true | InitSettings(verbose: true) |
| Test Mode | builder.testDeviceAdvertisingIdentifiers = ["«your-IDFA»"] | InitSettings(test: true) |
| SKAdNetwork IDs | Manual Info.plist update required | Manual Info.plist update required |
Ad Formats
Banner Ads
This section helps you migrate Banner Ad implementation from MAX to XMediator SDK.
Banner API Method Comparison
- Swift
- Objective-C
| Operation | MAX | XMediator |
|---|---|---|
| Set Delegate | adView.delegate = self | XMediatorAds.banner.addDelegate(self) |
| Load Banner | adView.loadAd() | XMediatorAds.banner.load(placementId:) |
| Show Banner | adView.isHidden = false | bannerView.isHidden = false |
| Operation | MAX | XMediator |
|---|---|---|
| Set Delegate | adView.delegate = self; | [X3MXMediatorAds.banner addDelegate:self]; |
| Load Banner | [adView loadAd]; | [X3MXMediatorAds.banner loadWithPlacementId:]; |
| Show Banner | adView.hidden = NO; | bannerView.hidden = NO; |
Delegate Method Comparison
- Swift
- Objective-C
| Event / Action | MAX (MAAdViewAdDelegate) | XMediator (BannerAdsDelegate) |
|---|---|---|
| Banner Loaded | func didLoad(_ ad: MAAd) | func didLoad(placementId: String, result: LoadResult) |
| Failed to Load | func didFailToLoadAd(forAdUnitIdentifier adUnitIdentifier: String, withError error: MAError) | Handled internally |
| Clicked | func didClick(_ ad: MAAd) | func didClick(placementId: String) |
| Failed to Display | func didFail(toDisplay ad: MAAd, withError error: MAError) | — |
| Impression Recorded | Not available by default | func didRecordImpression(placementId: String, data: ImpressionData) |
| Event / Action | MAX (MAAdViewAdDelegate) | XMediator (BannerAdsDelegate) |
|---|---|---|
| Banner Loaded | - (void)didLoadAd:(MAAd *)ad; | - (void)didLoadWithPlacementId:(NSString *)placementId result:(X3MLoadResult *)result; |
| Failed to Load | - (void)didFailToLoadAdForAdUnitIdentifier:(NSString *)adUnitIdentifier withError:(MAError *)error; | Handled internally |
| Clicked | - (void)didClickAd:(MAAd *)ad; | - (void)didClickWithPlacementId:(NSString *)placementId; |
| Failed to Display | - (void)didFailToDisplayAd:(MAAd *)ad withError:(MAError *)error; | — |
| Impression Recorded | Not available by default | - (void)didRecordImpressionWithPlacementId:(NSString *)placementId data:(X3MImpressionData *)data; |
info
Note: Impression callbacks are not available by default in MAX, and expand/collapse events are not exposed in XMediator.
Key Differences
| Feature | MAX | XMediator |
|---|---|---|
| Ad Identifier | Ad Unit ID | Placement ID |
| Ad Object | MAAdView | BannerView |
| Delegate Protocol | MAAdViewAdDelegate | BannerAdsDelegate |
| Impression Data | MAAd | via didRecordImpression |
| Layout Approach | Manual / Auto Layout | Auto Layout recommended |
Interstitial Ads
This section helps you migrate Interstitial Ad implementation from AppLovin MAX SDK to XMediator SDK.
Interstitial API Method Comparison
- Swift
- Objective-C
| Operation | MAX | XMediator |
|---|---|---|
| Set Delegate | interstitialAd.delegate = self | XMediatorAds.interstitial.addDelegate(self) |
| Load Interstitial | interstitialAd.load() | XMediatorAds.interstitial.load(placementId:) |
| Show Interstitial | interstitialAd.show() | XMediatorAds.interstitial.present(...) |
| Check Ready | interstitialAd.isReady | XMediatorAds.interstitial.isReady() / XMediatorAds.interstitial.isReady(withPlacementId:) |
| Operation | MAX | XMediator |
|---|---|---|
| Set Delegate | interstitialAd.delegate = self; | [X3MXMediatorAds.interstitial addDelegate:self]; |
| Load Interstitial | [interstitialAd loadAd]; | [X3MXMediatorAds.interstitial loadWithPlacementId:]; |
| Show Interstitial | [interstitialAd showAd]; | [X3MXMediatorAds.interstitial presentWithPlacementId:]; |
| Check Ready | [interstitialAd isReady] | [X3MXMediatorAds.interstitial isReady] / [X3MXMediatorAds.interstitial isReadyWithPlacementId:] |
info
In XMediator, isReady() returns true if any loaded ad is available, regardless of placement.
Use isReady(withPlacementId:) to check for a specific placement.
Built-in Behavior in XMediator
- ✅ Auto-loading: Ads automatically reload after being dismissed or failing to show.
- 🔁 Auto-retry: Failed loads are retried with exponential backoff.
- 🛠️ Manual retry logic is not required.
Delegate Method Comparison
- Swift
- Objective-C
| Event / Action | MAX (MAAdDelegate) | XMediator (InterstitialAdsDelegate) |
|---|---|---|
| Loaded | func didLoad(_ ad: MAAd) | func didLoad(placementId: String, result: LoadResult) |
| Failed to Load | func didFailToLoadAd(forAdUnitIdentifier adUnitIdentifier: String, withError error: MAError) | Not exposed — handled internally |
| Displayed | func didDisplay(_ ad: MAAd) | func didPresent(placementId: String) |
| Clicked | func didClick(_ ad: MAAd) | func didClick(placementId: String) |
| Dismissed | func didHide(_ ad: MAAd) | func didDismiss(placementId: String) |
| Failed to Present | func didFail(toDisplay ad: MAAd, withError error: MAError) | func failedToPresent(placementId: String, error: PresentError) |
| Will Dismiss | func willDismiss(placementId: String) | |
| Impression/Revenue | func didPayRevenue(_ ad: MAAd) | func didRecordImpression(placementId: String, data: ImpressionData) |
| Event / Action | MAX (MAAdDelegate) | XMediator (InterstitialAdsDelegate) |
|---|---|---|
| Loaded | - (void)didLoadAd:(MAAd *)ad; | - (void)didLoadWithPlacementId:(NSString *)placementId result:(X3MLoadResult *)result; |
| Failed to Load | - (void)didFailToLoadAdForAdUnitIdentifier:(NSString *)adUnitIdentifier withError:(MAError *)error; | Not exposed — handled internally |
| Displayed | - (void)didDisplayAd:(MAAd *)ad; (Deprecated for MREC) | - (void)didPresentWithPlacementId:(NSString *)placementId; |
| Failed to Present | - (void)didFailToDisplayAd:(MAAd *)ad withError:(MAError *)error; | - (void)failedToPresentWithPlacementId:(NSString *)placementId error:(NSError *)error; |
| Clicked | - (void)didClickAd:(MAAd *)ad; | - (void)didClickWithPlacementId:(NSString *)placementId; |
| Dismissed | - (void)didHideAd:(MAAd *)ad; (Deprecated for MREC) | - (void)didDismissWithPlacementId:(NSString *)placementId; |
| Will Dismiss | Not available | - (void)willDismissWithPlacementId:(NSString *)placementId; |
| Impression/Revenue | - (void)didPayRevenueForAd:(MAAd *)ad; | - (void)didRecordImpressionWithPlacementId:(NSString *)placementId data:(X3MImpressionData *)data; |
Key Differences
| Feature | MAX | XMediator |
|---|---|---|
| Ad Identifier | Ad Unit ID | Placement ID |
| Ad Object | MAInterstitialAd | Internal singleton via XMediatorAds.interstitial |
| Delegate Assignment | interstitialAd.delegate = self | XMediatorAds.interstitial.addDelegate(self) |
| Show Method | interstitialAd.show() | present(...) or present(withPlacementId:...) |
| Retry Behavior | Manual retry with backoff recommended | Automatic with exponential backoff |
| Impression Data | didPayRevenue(_:) | didRecordImpression(...) |
X3M Interstitial MAX Interstitial
Rewarded Ads
This section helps you migrate Rewarded Ad implementation from AppLovin MAX SDK to XMediator SDK.
Rewarded API Method Comparison
- Swift
- Objective-C
| Operation | MAX | XMediator |
|---|---|---|
| Set Delegate | rewardedAd.delegate = self | XMediatorAds.rewarded.addDelegate(self) |
| Load Rewarded | rewardedAd.load() | XMediatorAds.rewarded.load(placementId:) |
| Show Rewarded | rewardedAd.show() | XMediatorAds.rewarded.present(fromViewController: self, fromAdSpace: "rewarded-ad-space") |
| Operation | MAX | XMediator |
|---|---|---|
| Set Delegate | rewardedAd.delegate = self; | [X3MXMediatorAds.rewarded addDelegate:self]; |
| Load Rewarded | [rewardedAd loadAd]; | [X3MXMediatorAds.rewarded loadWithPlacementId:]; |
| Show Rewarded | [rewardedAd showAd]; | [X3MXMediatorAds.rewarded presentWithPlacementId:]; |
Built-in Behavior in XMediator
- ✅ Auto-loading: Ads automatically reload after being dismissed or failing to show.
- 🔁 Auto-retry: Failed loads are retried with exponential backoff.
- 🛠️ Manual retry logic is not required.
Delegate Method Comparison
- Swift
- Objective-C
| Event / Action | MAX (MARewardedAdDelegate) | XMediator (RewardedAdsDelegate) |
|---|---|---|
| Loaded | func didLoad(_ ad: MAAd) | func didLoad(placementId: String, result: LoadResult) |
| Failed to Load | func didFailToLoadAd(forAdUnitIdentifier adUnitIdentifier: String, withError error: MAError) | Not exposed — handled internally |
| Displayed | func didDisplay(_ ad: MAAd) | func didPresent(placementId: String) |
| Failed to Present | func didFail(toDisplay ad: MAAd, withError error: MAError) | func failedToPresent(placementId: String, error: PresentError) |
| Clicked | func didClick(_ ad: MAAd) | func didClick(placementId: String) |
| Closed/Dismissed | func didHide(_ ad: MAAd) | func didDismiss(placementId: String) |
| Will Dismiss | — | func willDismiss(placementId: String) |
| Impression/Revenue | func didPayRevenue(_ ad: MAAd) | func didRecordImpression(placementId: String, data: ImpressionData) |
| Rewarded | func didRewardUser(for ad: MAAd, with reward: MAReward) | func didEarnReward(placementId: String) |
| Event / Action | MAX (MARewardedAdDelegate) | XMediator (RewardedAdsDelegate) |
|---|---|---|
| Loaded | - (void)didLoadAd:(MAAd *)ad; | - (void)didLoadWithPlacementId:(NSString *)placementId result:(X3MLoadResult *)result; |
| Failed to Load | - (void)didFailToLoadAdForAdUnitIdentifier:(NSString *)adUnitIdentifier withError:(MAError *)error; | Not exposed — handled internally |
| Displayed | - (void)didDisplayAd:(MAAd *)ad; | - (void)didPresentWithPlacementId:(NSString *)placementId; |
| Failed to Present | - (void)didFailToDisplayAd:(MAAd *)ad withError:(MAError *)error; | - (void)failedToPresentWithPlacementId:(NSString *)placementId error:(NSError *)error; |
| Clicked | - (void)didClickAd:(MAAd *)ad; | - (void)didClickWithPlacementId:(NSString *)placementId; |
| Closed/Dismissed | - (void)didHideAd:(MAAd *)ad; | - (void)didDismissWithPlacementId:(NSString *)placementId; |
| Will Dismiss | — | - (void)willDismissWithPlacementId:(NSString *)placementId; |
| Impression/Revenue | - (void)didPayRevenueForAd:(MAAd *)ad; | - (void)didRecordImpressionWithPlacementId:(NSString *)placementId data:(X3MImpressionData *)data; |
| Rewarded | - (void)didRewardUserForAd:(MAAd *)ad withReward:(MAReward *)reward; | - (void)didEarnRewardWithPlacementId:(NSString *)placementId; |
Key Differences
| Feature | MAX | XMediator |
|---|---|---|
| Ad Identifier | Ad Unit ID | Placement ID |
| Ad Object | MARewardedAd.shared(...) | Singleton via XMediatorAds.rewarded |
| Delegate Assignment | rewardedAd.delegate = self | XMediatorAds.rewarded.addDelegate(self) |
| Show Method | rewardedAd.show() | present(...) or present(withPlacementId:...) |
| Manual Retry | Recommended | Not needed – auto-retries are built-in |
| Reward Callback | didRewardUser(...) | didReward(...) |
| Impression Data | via didPayRevenue | via didRecordImpression(...) |